<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
               "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Redirector Guide</title>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8"/>
<meta name="title" content="Redirector Guide"/>
<meta name="generator" content="Org-mode"/>
<meta name="generated" content="2012-04-03"/>
<meta name="author" content="Cyril Feng"/>
<meta name="description" content=""/>
<meta name="keywords" content=""/>
<style type="text/css">
 <!--/*--><![CDATA[/*><!--*/
  html { font-family: Times, serif; font-size: 12pt; }
  .title  { text-align: center; }
  .todo   { color: red; }
  .done   { color: green; }
  .tag    { background-color: #add8e6; font-weight:normal }
  .target { }
  .timestamp { color: #bebebe; }
  .timestamp-kwd { color: #5f9ea0; }
  .right  {margin-left:auto; margin-right:0px;  text-align:right;}
  .left   {margin-left:0px;  margin-right:auto; text-align:left;}
  .center {margin-left:auto; margin-right:auto; text-align:center;}
  p.verse { margin-left: 3% }
  pre {
	border: 1pt solid #AEBDCC;
	background-color: #F3F5F7;
	padding: 5pt;
	font-family: courier, monospace;
        font-size: 90%;
        overflow:auto;
  }
  table { border-collapse: collapse; }
  td, th { vertical-align: top;  }
  th.right  { text-align:center;  }
  th.left   { text-align:center;   }
  th.center { text-align:center; }
  td.right  { text-align:right;  }
  td.left   { text-align:left;   }
  td.center { text-align:center; }
  dt { font-weight: bold; }
  div.figure { padding: 0.5em; }
  div.figure p { text-align: center; }
  div.inlinetask {
    padding:10px;
    border:2px solid gray;
    margin:10px;
    background: #ffffcc;
  }
  textarea { overflow-x: auto; }
  .linenr { font-size:smaller }
  .code-highlighted {background-color:#ffff00;}
  .org-info-js_info-navigation { border-style:none; }
  #org-info-js_console-label { font-size:10px; font-weight:bold;
                               white-space:nowrap; }
  .org-info-js_search-highlight {background-color:#ffff00; color:#000000;
                                 font-weight:bold; }
  /*]]>*/-->
</style>
<style>table{margin:auto auto;}</style>
<style>body{padding:0 20px;}</style>
<style>i{font-weight:bold;}</style>
<style>code{background-color:lightgray;font-size:90%}</style>
<script type="text/javascript">
<!--/*--><![CDATA[/*><!--*/
 function CodeHighlightOn(elem, id)
 {
   var target = document.getElementById(id);
   if(null != target) {
     elem.cacheClassElem = elem.className;
     elem.cacheClassTarget = target.className;
     target.className = "code-highlighted";
     elem.className   = "code-highlighted";
   }
 }
 function CodeHighlightOff(elem, id)
 {
   var target = document.getElementById(id);
   if(elem.cacheClassElem)
     elem.className = elem.cacheClassElem;
   if(elem.cacheClassTarget)
     target.className = elem.cacheClassTarget;
 }
/*]]>*///-->
</script>

</head>
<body>

<div id="preamble">

</div>

<div id="content">
<h1 class="title">Redirector Guide</h1>





<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">1 Preface</a></li>
<li><a href="#sec-2">2 Conventions</a></li>
<li><a href="#sec-3">3 How it works</a></li>
<li><a href="#sec-4">4 Basic Usage</a>
<ul>
<li><a href="#sec-4-1">4.1 Protocols</a></li>
<li><a href="#sec-4-2">4.2 Manual Redirection</a></li>
<li><a href="#sec-4-3">4.3 Configure Rules</a></li>
<li><a href="#sec-4-4">4.4 Basic Syntax of Rules</a>
<ul>
<li><a href="#sec-4-4-1">4.4.1 Name</a></li>
<li><a href="#sec-4-4-2">4.4.2 Match</a></li>
<li><a href="#sec-4-4-3">4.4.3 Substitution</a></li>
<li><a href="#sec-4-4-4">4.4.4 Replacement</a></li>
</ul>
</li>
<li><a href="#sec-4-5">4.5 Test</a></li>
<li><a href="#sec-4-6">4.6 Debugger</a></li>
</ul>
</li>
<li><a href="#sec-5">5 Advanced Match</a></li>
<li><a href="#sec-6">6 Advanced Substitution &amp; Replacement</a></li>
<li><a href="#sec-7">7 Troubleshooting</a></li>
<li><a href="#sec-8">8 Suggestions</a>
<ul>
<li><a href="#sec-8-1">8.1 Composing efficient <i>Match</i> patterns</a></li>
<li><a href="#sec-8-2">8.2 Composing maintainable <i>Substitution</i>s</a></li>
</ul>
</li>
</ul>
</div>
</div>

<div id="outline-container-1" class="outline-2">
<h2 id="sec-1"><span class="section-number-2">1</span> Preface</h2>
<div class="outline-text-2" id="text-1">

<p>  This guide was created as an introduction to <i>Redirector</i>,
  the <i>Chromium</i> / <i>Google Chrome</i> extension that redirects URLs
  either automatically or manually.
  Rather than covering every aspect of <i>Redirector</i>,
  this guide will mainly focus on composing the rules.
</p>
</div>

</div>

<div id="outline-container-2" class="outline-2">
<h2 id="sec-2"><span class="section-number-2">2</span> Conventions</h2>
<div class="outline-text-2" id="text-2">

<dl>
<dt><i>Cr</i></dt><dd>The <i>Chromium</i> / <i>Google Chrome</i> browser

</dd>
<dt><i>RegExp</i></dt><dd>Regular expression

</dd>
<dt>=~</dt><dd>matches or is matched with

</dd>
<dt>!~</dt><dd>unmatches or is unmatched with

</dd>
<dt><code>&hellip;</code></dt><dd>Placeholder for the contents

</dd>
<dt>-&gt;</dt><dd>redirects to
</dd>
</dl>


</div>

</div>

<div id="outline-container-3" class="outline-2">
<h2 id="sec-3"><span class="section-number-2">3</span> How it works</h2>
<div class="outline-text-2" id="text-3">

<p>  <i>Redirector</i> handles every web request
  at the very beginning of its creation,
  when DNS resolving, connection to the server, etc have not started.
  Note that even when you browsing a single web-page,
  multiple web request is likely to be created, e.g., to load images.
  <i>Redirector</i> simply handles all of them.
</p>
<p>
  <i>Redirector</i> will first check if the URL of a request matches
  any of the automatic redirection rules,
  If so, the URL will be modified/blocked
  according to the <b>first</b> matched rule.
</p>
<p>
  <b>NOTE:</b>
  Such process <b>happens ONLY ONCE</b>.
  Actually the redirected URL will trigger the same process,
  which will be ignored by <i>Redirector</i>.
  The same thing happens to a server-initiated redirection.
  This mechanism ensures that
  no (infinite) redirection loop will be created,
  which easily freezes <i>Cr</i>.
  In fact, even if <i>Redirector</i> carries out a second redirection,
  no third one will be triggered,
  as it's an intrinsic security feature of <i>Cr</i>.
</p>
<p>
  A manual redirection is just like a forced process of above,
  without match checking.
</p>
<p>
  It's another independent yet analogous process
  for <i>Redirector</i> to manipulate HTTP request headers.
  If there're any rules matching the URL of a web request,
  the first will be picked up to modify the headers.
</p>
<p>
  <b>NOTE:</b>
  Such process normally <b>happens ONLY ONCE</b>,
  but there's an exception:
  if a server-initiated redirection is triggered,
  <i>Redirector</i> will try to modify its headers again.
  It's because previous headers have been sent and
  totally new headers have been generated.
</p>
<p>
  <i>Redirector</i> comes with a debugger,
  ideal for monitoring processes mentioned above.
  It can help you to better understand
  the internal time sequential relationship.
  For example, you will notice that headers handling always
  takes place after a redirection checking.
  If a redirection occurs after headers handling,
  then it's probably a server-initiated redirection.
</p>
</div>

</div>

<div id="outline-container-4" class="outline-2">
<h2 id="sec-4"><span class="section-number-2">4</span> Basic Usage</h2>
<div class="outline-text-2" id="text-4">

<p>  In this part,
  you're about to learn how to configure <i>Redirector</i> and compose basic rules.
</p>

</div>

<div id="outline-container-4-1" class="outline-3">
<h3 id="sec-4-1"><span class="section-number-3">4.1</span> Protocols</h3>
<div class="outline-text-3" id="text-4-1">

<p>   Normally,
   <i>Redirector</i> handles <code>HTTP://</code>, <code>HTTPS://</code>, <code>FTP://</code> and <code>FILE://</code> protocols,
   but you may want to disable some of them in <i>Preferences</i> tab.
</p>
<p>
   <b>NOTE:</b>
   If you ever managed to get <i>Redirector</i> manipulating URLs begin with other protocol
   e.g. <code>chrome://</code>, don't rely on that.
</p>
</div>

</div>

<div id="outline-container-4-2" class="outline-3">
<h3 id="sec-4-2"><span class="section-number-3">4.2</span> Manual Redirection</h3>
<div class="outline-text-3" id="text-4-2">

<p>   <i>Redirector</i> is mainly used to redirect URLs automatically,
   while there're many situations auto-redirection is unfit for.
   As an alternative, you should consider manual redirection.
</p>
<p>
   There're basically two ways:
</p><ul>
<li>Right click on a link and select a rule,
     the link will be loaded in a new tab with the rule appling to its URL;
</li>
<li>Right click on a page and select a rule,
     this page will be reloaded with the rule appling to it's URL.
</li>
</ul>


<p>
   <b>NOTE:</b>
   You need at least one <a href="#sec-4-4-2-3">Manual rule</a> created and enabled,
   or there won't be anything about <i>Redirector</i> in context menus.
</p>
</div>

</div>

<div id="outline-container-4-3" class="outline-3">
<h3 id="sec-4-3"><span class="section-number-3">4.3</span> Configure Rules</h3>
<div class="outline-text-3" id="text-4-3">

<p>   To add a rule, press the plus button,
   so the rule editor will turn up.
   You may either select a built-in rule or compose one yourself.
</p>
<p>
   <b>NOTE:</b> built-in rules are for reference use only. Some of them
   are just skeletons, useless without modifications.
</p>
<p>
   You may press &lt;Enter&gt; key or double click on the a rule to edit it,
   or press &lt;Delete&gt; key to delete it.
   If multiple rules are created, their priorities can be changed through
   j/k, arrow keys or mouse draging.
</p>
<p>
   <b>NOTE:</b> Rules are searched from top to bottom, with disabled ones
   ignored.
</p>
<p>
   Make a backup of the rules list with <i>Backup</i>,
   and the backup file will be downloaded.
   Restorations are done with <i>Restore</i>.
   You may also choose a rule and export it.
   Importation is the reverse process of it.
   For online rules (e.g. as attachments),
   you may right click on that link and select "import this rule".
</p>
</div>

</div>

<div id="outline-container-4-4" class="outline-3">
<h3 id="sec-4-4"><span class="section-number-3">4.4</span> Basic Syntax of Rules</h3>
<div class="outline-text-3" id="text-4-4">


</div>

<div id="outline-container-4-4-1" class="outline-4">
<h4 id="sec-4-4-1"><span class="section-number-4">4.4.1</span> Name</h4>
<div class="outline-text-4" id="text-4-4-1">

<p>    The name of the rule. Make it as distinctive as possible.
</p>
</div>

</div>

<div id="outline-container-4-4-2" class="outline-4">
<h4 id="sec-4-4-2"><span class="section-number-4">4.4.2</span> Match</h4>
<div class="outline-text-4" id="text-4-4-2">

<p>    A <i>Match</i> pattern defines which URLs this rule will apply to.
    You may want to check the option <i>Ignore case</i> to perform a
    case-insensitive match.
    You may specify which content this rule apply to:
</p><dl>
<dt>All types</dt><dd>all of the types below
</dd>
<dt>Main Frame</dt><dd>the top-level frame, whose address is displayed in the address bar
</dd>
<dt>Sub Frame</dt><dd>embedded frames
</dd>
<dt>CSS</dt><dd>stylesheets
</dd>
<dt>Script</dt><dd>JavaScript, Tcl, etc
</dd>
<dt>Image</dt><dd>inline images (&lt;img&gt; elements)
</dd>
<dt>Object</dt><dd>videos, audios, some kind of images, etc
</dd>
<dt>XHR</dt><dd>XMLHttpRequest
</dd>
<dt>Other</dt><dd>
</dd>
</dl>

<p>    To determine which type a content really belongs to,
    please seek help from the debugger.
</p>
<p>
    <i>Match</i> patterns are typically in three forms:
</p><ul>
<li id="sec-4-4-2-1"><i>RegExp</i><br/>
     Matching with <i>RegExp</i> will be introduced in
     <a href="#sec-5">Advanced Match</a>

</li>
</ul>
<ul>
<li id="sec-4-4-2-2">Wildcard<br/>
     Wildcards are normal strings, except for two special characters:
<dl>
<dt><code>?</code></dt><dd>Matches any single character. e.g.
<ul>
<li><code>https://www.google.com.??/</code>
                =~ <code>https://www.google.com.hk/</code>.

</li>
</ul>

</dd>
<dt><code>*</code></dt><dd>Matches any string, including an empty one, e.g.
<ul>
<li><code>https://*google.com/</code>
                =~ <code>https://www.google.com/</code>
                and =~ <code>https://google.com/</code>.
</li>
</ul>

</dd>
</dl>


<p>
     <b>NOTE:</b>
</p><ul>
<li>If you want to match these two characters literally, use
       <code>\?</code> and <code>\*</code> instead.
</li>
<li>A URL matches a <i>Match</i> pattern so long as part of it matches.
       For strict matching, see <i>Smart wildcard</i>.
</li>
</ul>


</li>
</ul>
<ul>
<li id="sec-4-4-2-3"><a name="BASIC-MATCH-MANUAL" id="BASIC-MATCH-MANUAL"></a>Manual<br/>
     A special type of <i>Match</i> method, indicating this rule is used
     for manual redirection.

</li>
</ul>
<ul>
<li id="sec-4-4-2-4">Smart wildcard<br/>
     <i>Smart wildcard</i> was introduced to facilitate
     the composing of <i>Match</i> patterns.
     Features:
<ul>
<li>Smart wildcard do strictly matching
</li>
<li>Patterns without the protocol part will match
       either <a href="http://">http://</a> or <a href="https://">https://</a>
</li>
<li>For patterns without paths, query strings and fragment identifiers,
       A implied slash will be automatically appended.
</li>
</ul>


</li>
</ul>
</div>

</div>

<div id="outline-container-4-4-3" class="outline-4">
<h4 id="sec-4-4-3"><span class="section-number-4">4.4.3</span> Substitution</h4>
<div class="outline-text-4" id="text-4-4-3">

<p>    A <i>Substitution</i> defined which part(s) of a URL should be replaced.
    Case-insensitive search is enabled by checking <i>Ignore case</i>,
    and search won't stop on the first match when <i>Global match</i> is checked.
    <i>Substitution</i>s are also in three forms:
</p><ul>
<li id="sec-4-4-3-1"><i>RegExp</i><br/>
     Substituting with <i>RegExp</i> will be explained in
     <a href="#sec-6">Advanced Substitution &amp; Replacement</a>.

</li>
</ul>
<ul>
<li id="sec-4-4-3-2">Wildcard<br/>
     Same with that of <i>Match</i>.

</li>
</ul>
<ul>
<li id="sec-4-4-3-3">Block<br/>
     Instead of redirecting a URL, you may alternatively block it.

</li>
</ul>
<ul>
<li id="sec-4-4-3-4">Header<br/>
     This option allows you to modify "HTTP request headers".
     <i>Substitution</i> stands for the name of the header to be modified.
     If a header is not found, then it'll be created.
     To delete a header,
     place a minus sign <code>-</code> in front of its name.
     To modify multiple headers,
     seperate thme by vertical lines <code>|</code>.

</li>
</ul>
</div>

</div>

<div id="outline-container-4-4-4" class="outline-4">
<h4 id="sec-4-4-4"><span class="section-number-4">4.4.4</span> Replacement</h4>
<div class="outline-text-4" id="text-4-4-4">

<p>    A <i>Replacement</i> is what used to replace the <i>Substitution</i>.
    You may simply use a string,
    but a literal dollar sign <code>$</code> should be written as <code>$$</code>,
    as
    <a href="#sec-6">Advanced Substitution &amp; Replacement</a>
    requires it.
</p>
<p>
    You may check the <i>Decode URL</i> option,
    which results in the encoded characters of the final URL replaced
    with the corresponding ones, e.g.
</p><ul>
<li><code>http%3A%2F%2Fwww.google.com%2F</code> to <code>http://www.google.com/</code>.
</li>
</ul>


<p>
    Note that <i>Replacement</i> for <i>Substitution</i> of type header differs.
    Here it's the corresponding values of headers also seperated by <code>|</code>.
    Use <code>\|</code> instead if a value contains a literal <code>|</code>.
    You may leave the value blank if header is to be deleted.
</p>
</div>
</div>

</div>

<div id="outline-container-4-5" class="outline-3">
<h3 id="sec-4-5"><span class="section-number-3">4.5</span> Test</h3>
<div class="outline-text-3" id="text-4-5">

<p>   You are encouraged to test every rules you composed,
   or <i>Cr</i> would probably freeze up or complain "He's Dead, Jim!".
   An easy test utility is included in the rule editor.
   Here're only some tips:
</p>
<ul>
<li>When making a new rule,
     select <i>Match</i> as <i>Manual</i> and compose <i>Substitution</i> together with <i>Replacement</i> first.
     You should never move on until the test passed.
     Save <i>Substitution</i> and <i>Replacement</i> before composing <i>Match</i>.

</li>
<li>When debugging an existing rule,
     simplify the potential buggy parts first.
     If you get one rule messed up, discard changes and start from scratch.
</li>
</ul>


<p>
   If every thing works, the test result will show up with substituted
   part and its replacement colored.
</p>
</div>

</div>

<div id="outline-container-4-6" class="outline-3">
<h3 id="sec-4-6"><span class="section-number-3">4.6</span> Debugger</h3>
<div class="outline-text-3" id="text-4-6">

<p>   Debugger is introduced since <i>Redirector</i> ver.2.2.8
   to make it easier to find out problems with rules.
   Matters need attention:
</p>
<ul>
<li>First lines of each debug record indicate the time sequence.
     Time of first record is in the form of <code>[hh:mm:ss]</code> and
     others in <code>[+ElapsedTimeInMilliseconds ms]</code>.

</li>
<li>The <i>Test speed</i> option is surely to delay the whole debug session
     since <i>Redirector</i> has to test for one million times to get the result.
     That is to say,
     if a redirection takes up 0.5<span>&mu;</span>s to finish,
     you're likely to experience a delay of 0.5s.

</li>
<li>Sum of time elapsed in redirection and headers modification is
     an estimation of how long <i>Redirector</i> will take in reality.
</li>
</ul>


<p>
   <b>WARN:</b> Redirector will temporarily put normal works aside
   until debugging session finishes
   (when you click on the stop button,
   close the debugee tab or quit the options page).
</p>
</div>
</div>

</div>

<div id="outline-container-5" class="outline-2">
<h2 id="sec-5"><a name="ADVANCED_MATCH" id="ADVANCED_MATCH"></a><span class="section-number-2">5</span> Advanced Match</h2>
<div class="outline-text-2" id="text-5">

<p>  <i>Advanced Match</i>es are achieved with the aid of <i>RegExp</i>.
  You may refer to other guides on <i>RegExp</i>,
  but keep in mind that there're various forms,
  and what you employ here is of JavaScript flavor,
  one fork of Perl flavor <i>RegExp</i>.
</p>
<p>
  As it's impossible to show you all facts about <i>RegExp</i> in so short
  a guide,
  here we will only cover those have something to do with URL matching,
  and draw out their meanings only applicable to real URLs.
</p>
<p>
  One basic component of <i>RegExp</i> is meta-characters, characters with
  special meanings, as the table below presents:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Meta-Character</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>\</code></td><td class="left">Escape the next character</td></tr>
<tr><td class="left"><code>^</code></td><td class="left">Matches the beginning of a URL</td></tr>
<tr><td class="left"><code>$</code></td><td class="left">Matches the end of a URL</td></tr>
<tr><td class="left"><code>.</code></td><td class="left">Matches any character</td></tr>
<tr><td class="left"><code>&#124;</code></td><td class="left">Alternation</td></tr>
</tbody>
<tbody>
<tr><td class="left"><code>[&hellip;]</code></td><td class="left">Character class</td></tr>
<tr><td class="left"><code>[^&hellip;]</code></td><td class="left">Antonym of <code>[&hellip;]</code></td></tr>
</tbody>
</table>


<p>
  If you want to match a meta-character (or a quantifier, see below) literally,
  a backslash is required to escape the special meaning,
  e.g.
</p><ul>
<li><code>https://www\.gogole\.com/</code>
    =~ <code>https://www.google.com/</code>.
</li>
</ul>


<p>
  <code>^</code> and <code>$</code> are both anchors, which match specific positions rather
  than any real characters, e.g.
</p><ul>
<li><code>^https://</code> =~ <code>https://www.google.com/</code>
    while !~ <code>http://www.google.com/search?q=https</code>.
</li>
</ul>


<p>
  Besides <code>^</code> and <code>$</code>, there're other anchors, belonging to the
  <i>Escape Sequences</i>:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Anchor</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>\b</code></td><td class="left">Matches the border of a word</td></tr>
<tr><td class="left"><code>\B</code></td><td class="left">Antonym of <code>\b</code></td></tr>
</tbody>
</table>


<p>
  <code>|</code> means alternation, e.g.
</p><ul>
<li><code>https://www.google.com</code> =~ <code>google|yahoo</code>
    while !~ <code>http://www.bing.com</code>.
</li>
</ul>


<p>
  Actually, <code>|</code> is more useful in <i>groups</i>.
</p>
<p>
  A character class is a group of characters that it matches, e.g.
</p><ul>
<li><code>[aA]</code> =~ either <code>a</code> or <code>A</code>
</li>
</ul>


<p>
  Hyphens <code>-</code> in character classes mean a range of characters in
  ASCII table, e.g.
</p><ul>
<li><code>[a-z]</code> =~ any lowercase letter
</li>
<li><code>[0-9]</code> =~ any digit
</li>
</ul>


<p>
  <b>NOTE:</b>
  To place a literal hyphen in a character class,
  use <code>\-</code> instead.
  <code>-</code> is literal in other context.
</p>
<p>
  There're some predefined "character classes",
  also in the form of <i>Escape Sequences</i>:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Escape Sequence</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>\w</code></td><td class="left">Matches a word character (alphanum, underscore)</td></tr>
<tr><td class="left"><code>\W</code></td><td class="left">Antonym of <code>\w</code></td></tr>
<tr><td class="left"><code>\d</code></td><td class="left">Matches a digit</td></tr>
<tr><td class="left"><code>\D</code></td><td class="left">Antonym of <code>\d</code></td></tr>
<tr><td class="left"><code>\ddd</code></td><td class="left">Matches the No.ddd (OCT) ASCII character</td></tr>
<tr><td class="left"><code>\xdd</code></td><td class="left">Matches the No.dd (HEX) ASCII character</td></tr>
<tr><td class="left"><code>\udddd</code></td><td class="left">Matches the No.dddd (HEX) Unicode character</td></tr>
</tbody>
</table>


<p>
  Another basic component of <i>RegExp</i> is quantifiers,
  they're used as suffixes after characters, meta-characters or <i>groups</i>,
  to indicate how many time the character should be repeated:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Quantifier</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>*</code></td><td class="left">Zero or more, as many as possible</td></tr>
<tr><td class="left"><code>+</code></td><td class="left">At least one, as many as possible</td></tr>
<tr><td class="left"><code>?</code></td><td class="left">Zero or one, as many as possible</td></tr>
<tr><td class="left"><code>{N}</code></td><td class="left">Exactly N</td></tr>
<tr><td class="left"><code>{N,}</code></td><td class="left">At least N, as many as possible</td></tr>
<tr><td class="left"><code>{N,M}</code></td><td class="left">Between N and M, as many as possible</td></tr>
</tbody>
</table>


<p>
  e.g.
</p><ul>
<li><code>^https://www\.google\.com/*</code>
    =~ any URL begins with <code>https://www.google.com/</code>;
</li>
<li><code>^http?://</code>
    =~ any URL begins with <code>http://</code> or <code>https://</code>.
</li>
</ul>


<p>
  By default, <i>Redirector</i> matches in "greedy" mode,
  which means it will match as many characters as possible.
  Place a <code>?</code> after the quantifier to turn it to "lazy" mode,
  e.g.
</p><ul>
<li><code>https://.*?\.</code> will match <code>https://www.</code> in string
    <code>https://www.google.com</code>
    while <code>https://.*\.</code> will match <code>https://www.google.</code>.
</li>
</ul>


<p>
  One pattern can be isolated through the use of parentheses, called
  <i>grouping</i>:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Grouping</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>(&hellip;)</code></td><td class="left">Capturing grouping</td></tr>
<tr><td class="left"><code>(?:&hellip;)</code></td><td class="left">Non-capturing grouping</td></tr>
</tbody>
</table>


<p>
  Contents in capturing groups are automatically saved in special
  variables <code>\1</code> to <code>\99</code>,
  numbered from left to right, from outside to inside.
  Capturing groups can do <i>back reference</i>,
  e.g.
</p><ul>
<li><code>http://(\w+)\.wikipedia\.org/\1/</code> =~
    <code>http://zh.wikipedia.org/zh/Google</code>
    while !~ <code>http://zh.wikipedia.org/zh-cn/Google</code>
</li>
</ul>


<p>
  In <i>RegExp</i>, <i>Extended Pattern</i> is of the form
  <code>(?x&hellip;)</code>, e.g. <code>(?:&hellip;)</code>.
  Here are the rest:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Extended Pattern</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>(?=&hellip;)</code></td><td class="left">Followed by <code>&hellip;</code></td></tr>
<tr><td class="left"><code>(?!&hellip;)</code></td><td class="left">Antonym of <code>(?=&hellip;)</code></td></tr>
</tbody>
</table>


<p>
  The pattern <code>(?!&hellip;)</code> is quite useful,
  as <i>Redirector</i> doesn't come with the so-called <i>blacklist</i>,
  because you can completely avoid its use.
  For example, for a rule matching <code>A</code> but not matching <code>B</code>,
  you may compose it as <code>^(?!.*B).*A</code>.
  e.g.
</p><ul>
<li>Compose a <i>Match</i> pattern matching all URL belong to google.com
    and its subdomains but code.google.com:
<ul>
<li><code>^(?!.*https?://code\.google\.com)https?://(.*?\.)?google\.com</code>
</li>
<li>A more compact one:
      <code>^https?://(?!code)(.*?\.)?google.com</code>
</li>
</ul>

</li>
</ul>


<p>
  <b>Note:</b>
  <code>(?=&hellip;)</code> or <code>(?!&hellip;)</code> captures nothing.
</p>
</div>

</div>

<div id="outline-container-6" class="outline-2">
<h2 id="sec-6"><a name="ADVANCED_SUBSTITUTION" id="ADVANCED_SUBSTITUTION"></a><span class="section-number-2">6</span> Advanced Substitution &amp; Replacement</h2>
<div class="outline-text-2" id="text-6">

<p>  As well as matching, <i>RegExp</i> is a powerful tool for substitution.
  Syntax here is similar, we only discuss the differences.
</p>
<p>
  The main difference is <i>grouping</i>, while contents in capturing
  groups can also be used in <i>Replacement</i>.
  To be on the safe side, always replace capturing groups with
  non-capturing ones if they're not intended to be captured.
</p>
<p>
  Rather than being a literal string, <i>Replacement</i> can also
  be part of <i>Substitution</i>.
  This is achieved with the dollar sign <code>$</code>:
</p>
<table border="2" cellspacing="0" cellpadding="6" rules="groups" frame="hsides">
<caption></caption>
<colgroup><col class="left" /><col class="left" />
</colgroup>
<thead>
<tr><th scope="col" class="left">Special replacement</th><th scope="col" class="left">Meaning</th></tr>
</thead>
<tbody>
<tr><td class="left"><code>$N</code> (<code>$1</code> - <code>$99</code>)</td><td class="left">Matched content in the Nth capturing group</td></tr>
<tr><td class="left"><code>$&amp;</code></td><td class="left">What <i>Substitution</i> matches</td></tr>
<tr><td class="left"><code>$`</code></td><td class="left">The unmatched part on the left of <code>$&amp;</code></td></tr>
<tr><td class="left"><code>$'</code></td><td class="left">The unmatched part on the right of <code>$&amp;</code></td></tr>
</tbody>
</table>


<p>
  <code>$1</code> - <code>$99</code> are corresponding to <code>\1</code> - <code>\99</code> in
  <a href="#sec-5">Advanced Match</a>.
</p>
<p>
  Here're some examples:
</p><ul>
<li>With <i>Substitution</i> being <code>(^[^\.]+[^/]+)/[^/]*</code>
    and <i>Replacement</i> being <code>$1/zh-cn</code>,
    <code>http://zh.wikipedia.org/zh-hk/Google</code>
    -&gt; <code>http://zh.wikipedia.org/zh-cn/Google</code> ；

</li>
<li>With <i>Substitution</i> being <code>[^\.]+[^/]+</code>
    and <i>Replacement</i> being <code>$&amp;.sixxs.org</code>,
    <code>http://www.google.com/</code> -&gt; <code>http://www.google.com.sixxs.org/</code>.
</li>
</ul>


<p>
  <b>NOTE:</b>
  For an <i>anchor</i>, <i>Replacement</i> is inserted to the matched position,
  e.g.
</p><ul>
<li>With <i>Substitution</i> being <code>$</code> and <i>Replacement</i> being <code>ncr</code>,
    <code>http://www.google.com/</code> -&gt; <code>http://www.google.com/ncr</code>.
</li>
</ul>


</div>

</div>

<div id="outline-container-7" class="outline-2">
<h2 id="sec-7"><span class="section-number-2">7</span> Troubleshooting</h2>
<div class="outline-text-2" id="text-7">

<p>  For the sake of efficiency,
  <i>Redirector</i> doesn't do strict check with a rule during run-time.
  As a result, you may run into this problem:
</p>
<dl>
<dt>The bottom-left corner shows "Waiting for extension <i>Redirector</i>"</dt><dd>
<p>
    This indicates you probably got a bad rule
    that matches the current URL
    but makes <i>Redirector</i> puzzled on how to manipulate it.
</p></dd>
</dl>


<p>
  If you are sure a problem results from bugs of <i>Redirector</i>,
  send a bug report to &lt;CyrilFeng at gmail dot com&gt;.
  Before that, make sure you've gone through the following steps:
</p><ul>
<li>Make sure the problem will disappear once <i>Redirector</i> is disabled;

</li>
<li>Make sure you've installed the latest release (both <i>Cr</i> and <i>Redirector</i>);

</li>
<li>When recreate the problem, set the language of <i>Redirector</i> to
    Chinese or English if possible;

</li>
<li>Problem should be described in either Chinese or English;

</li>
<li>Export the problematic rule(s) together with the debugging results,
    then submit them with the report.
</li>
</ul>


</div>

</div>

<div id="outline-container-8" class="outline-2">
<h2 id="sec-8"><span class="section-number-2">8</span> Suggestions</h2>
<div class="outline-text-2" id="text-8">


</div>

<div id="outline-container-8-1" class="outline-3">
<h3 id="sec-8-1"><span class="section-number-3">8.1</span> Composing efficient <i>Match</i> patterns</h3>
<div class="outline-text-3" id="text-8-1">

<p>   The Quality of <i>Match</i> patterns is the key factor that affecting
   the efficiency of <i>Redirector</i>.
</p>
<p>
   Something must be clarified first:
</p><ul>
<li>Disabled rules and rules for manual redirections have nothing to do with the efficiency;

</li>
<li>Though wildcards are translated into <i>RegExp</i> internally,
     the translation only happens when <i>Redirector</i> starts or rules list has any change;

</li>
<li>To speed up, <i>RegExp</i>s are all compiled in advance.
     Even if you don't adopt any suggestion here,
     <i>Redirector</i> will be fast enough when doing matches.
</li>
</ul>


<p>
   To write an efficient <i>Match</i> pattern, you should:
</p><dl>
<dt>Prefer <i>RegExp</i> to wildcard</dt><dd>
<p>
     <i>RegExp</i> is more precise in matching;
</p>
</dd>
<dt>Avoid the use of <i>Ignore case</i></dt><dd>
<p>
     URLs are commonly in lower-case;
</p>
</dd>
<dt>Make matching process for unmatched URLs terminate as soon as possible</dt><dd>
<p>
      e.g.
</p><ul>
<li>If you want to match a URL begins with <code>http://</code>,
       then <code>^http://</code> is better than <code>http://</code>.

</li>
</ul>

</dd>
<dt>Prefer "lazy" mode to "greedy" mode</dt><dd>
<p>
     This is tenable when the matching part is short;
</p></dd>
</dl>


<p>
   In addition, you should keep rules for auto-redirection in a reasonable order.
</p>
</div>

</div>

<div id="outline-container-8-2" class="outline-3">
<h3 id="sec-8-2"><span class="section-number-3">8.2</span> Composing maintainable <i>Substitution</i>s</h3>
<div class="outline-text-3" id="text-8-2">

<p>   As <i>Cr</i> is not redirecting URLs all the time
   (or you've misused <i>Redirector</i>),
   You should ensure a <i>Substitution</i> is of maintainability first.
   To do so, you should:
</p><dl>
<dt>Make <i>Substitution</i> short</dt><dd>
<p>
     e.g.
</p><dl>
<dt>Remove unneccessary parts</dt><dd>
<ul>
<li>Preceding and Trailing <code>.*</code>, <code>.+</code>, etc are all unneccessary,
         use <code>$`</code>, <code>$'</code> in <i>Replacement</i> instead.

</li>
</ul>

</dd>
<dt>Some frequently-used <i>Substitution</i> patterns</dt><dd>
<dl>
<dt><code>https?://</code></dt><dd>
<p>
         =~ <code>http://</code> and <code>https://</code>;
</p>
</dd>
<dt><code>^[^\.]+[^/]+</code></dt><dd>
<p>
           =~ <code>protocol://[username[:password]@]domain[:port]</code>
           (square brackets means optional here).
</p>
</dd>
</dl>

</dd>
</dl>

</dd>
<dt>Prefer non-capturing groups to capturing ones</dt><dd>
<p>
     This help to avoid miscounting <code>$1</code>, <code>$2</code>&hellip;
</p></dd>
</dl>



<hr/>
</div>
</div>
</div>
</div>

<div id="postamble">
<p class="date">Date: 2012-04-03</p>
<p class="author">Author: Cyril Feng</p>
<p class="creator">Org version 7.8.03 with Emacs version 23</p>
<a href="http://validator.w3.org/check?uri=referer">Validate XHTML 1.0</a>

</div>
</body>
</html>
